Pinging @elastic/es-docs (>docs)

Pinging @elastic/es-search (:Search/Analysis)

What is the value in introducing another nav layer with the "concepts" bucket? I feel like this approach is going to proliferate more content-free nav pages that users land on and have to click through. For the ML book, it's just one page, but if we do this throughout the ES ref, we're going to have a bunch of concept link-farms.

If we want to adopt a "page per concept" model (for SEO?), is there a reason that they aren't just part of the Overview section? I sort of feel like introducing the concepts that are central to a feature is the whole point of the overview sections.

I can see the value in having a consistent approach across the doc set, but this feels like it's inclined to propagate patterns that we know are problematic: content-free pages and a lot of short pages.

Thanks for your feedback @debadair. Responses below.

What is the value in introducing another nav layer with the "concepts" bucket?

It explicitly labels conceptual docs, differentiating them from other types of documentation.

Making this explicit helps guide our users. It lets them know what kind of content to expect in the bucket.

It also helps guide contributors, who know what type of content to place here, and serves as a quick indicator of whether content for a particular concept already exists.

I feel like this approach is going to proliferate more content-free nav pages that users land on and have to click through.

This is a feature, not a bug. If a user lands on this page, they are likely looking for broad information ("Elasticsearch analysis concepts") or the content they want likely doesn't exist. This nav page helps orient the user in both cases.

For the ML book, it's just one page, but if we do this throughout the ES ref, we're going to have a bunch of concept link-farms.

It's two pages:

• Anomaly detection concepts
• DFA concepts

Regardless, I'm confused about why this would be permissible as a one-off but not a pattern. Bad practice is bad practice?

If we want to adopt a "page per concept" model (for SEO?), is there a reason that they aren't just part of the Overview section?

There are a few reasons:

• "Overview" does not explicitly label the docs as "conceptual documentation"
• The overview content is not conceptual documentation. The overview helps the user learn what problems the feature solves and when they should use it. Conceptual docs go deeper and explain how the feature works, including the specific components used.
• It allows users to explore and read about subtopics individually rather than dumping all the information at once.

I can see the value in having a consistent approach across the doc set, but this feels like it's inclined to propagate patterns that we know are problematic: content-free pages and a lot of short pages.

Aside from anecdotes, how do we know navigation pages are problematic?

Anecdotally, I've heard feedback both from users and Elastic leadership that our docs often contain "walls of text." As stated above, I think the nav page gives users and contributors good guideposts.

Another thing @szabosteve and I have considered is using metadata to indicate content types, so that when we have a better navigation structure, users can filter on different content types. We aren't at the implementation stage yet, but I've played around with inserting this type of metadata in elastic/stack-docs#802
I've just put "concepts" and "reference" in there for now, but if we go forward we might want to consider what other types are applicable across multiple books and useful to users. And what other types of metadata (e.g. audience) are useful.

Thanks @szabosteve!

Backport commits

master: 0605eb2
7.x: ef26763
7.6: 0e29443
7.5: 0605eb2